home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / mthr25 / mthread.txt < prev    next >
Text File  |  1995-03-29  |  11KB  |  272 lines
  1. MTHREAD.TXT for MicroThread V2.5
  2.  
  3. This file contains details of the various MicroThread functions and 
  4. how to use them.
  5.  
  6. ---------------------------------------------------------------------
  7.  
  8. void MTInitialise(void);
  9.  
  10. Before you can use MicroThread in your program, you will have to 
  11. initialise it by calling this function. In fact, you will need to 
  12. call this function every time you want to start a new multi-threading 
  13. session. That is, once the function MTStartMultiThreading() returns, 
  14. MicroThread has been put back into an un-initialised state, and 
  15. MTInitialise() will need to be call again if you want to re-start 
  16. multi-threading.
  17.  
  18. ---------------------------------------------------------------------
  19.  
  20. enum MTReturnCode MTStartMultiThreading(void);
  21.  
  22. This function starts the MicroThread scheduler and thus multi-
  23. threading. All threads which have been created usng MTAddNewThread() 
  24. will start executing concurrently. MTStartMultiThreading will return 
  25. if thee is an error condition or if one of the thread executes the 
  26. function MTEndMultiThreading(). When MTStartMultiThreading() returns, 
  27. its return value would indicate the terminating conditions, which 
  28. would be one of the following:
  29.  
  30. enum MTReturnCode { 
  31.     NORMAL, 
  32.     DEADLOCKED, 
  33.     CTRLBREAK,
  34.     NOT_INITIALISED,
  35.     TOO_DEEP_CRITICAL_NEST 
  36. };
  37.  
  38. NORMAL indicates a normal exit, usually as a result of calling 
  39. MTEndMultiThreading(). DEADLOCKED means that the scheduler wasn't 
  40. able to find a thread to dispatch, so all the active threads must be 
  41. deadlocked. The scheduler can also be easily fooled by the fact that 
  42. all the threads have ended and thus assume that no thread = deadlock. 
  43. CTRLBREAK basically indicates that multi-threading was stopped by the 
  44. user hitting Control-BREAK. NOT_INITIALISED is obvious. 
  45. TOO_DEEP_CRITICAL_NEST is returned if one of the threads calls 
  46. MTEnterCritical() too many times without calling MTLeaveCritical().
  47.  
  48. ---------------------------------------------------------------------
  49.  
  50. int MTAddNewThread(PThreadFunc pThreadFunc, unsigned priority, 
  51. unsigned sizeArg, void *pArg);
  52.  
  53. This function creates and adds a new thread to the scheduler's READY 
  54. queue, ready to be activated by the scheduling. Threads can only be 
  55. added after MTInitialise() has been called. Threads can be added 
  56. before MTStartMultThreading() or by one or more of the threads when 
  57. multi-threading. The first parameter, pThreadFunc, is a pointer to 
  58. the function which is to execute as a thread, and is of the type:
  59.  
  60. typedef int (far *PThreadFunc) (void *pArg);
  61.  
  62. The second parameter is the priority of the thread, from 1 to 5, with 
  63. 1 being the lowest priority and 5 being the highest priority. The 
  64. parameter sizeArg describes the size of the memory block pointed to 
  65. by the next parameter *pArg, which is passed as an argument to the 
  66. thread function. A copy of this block of memory is made to another 
  67. area before the function returns, thus you can deallocate the 
  68. original memory when the function returns. The scheduler will take 
  69. care of deallocating the copy when the thread terminates. If you pass 
  70. a NULL for pArg, sizeArg is ignored, and no copy will be made.
  71.  
  72. There are two macros which are just variations on this funtion call: 
  73. MTAddThread(pThreadFunc, priority) which are more convenient for 
  74. functions which don't take parameters, and 
  75. MTAddArgThread(pThreadFunc, priority, sizeArg, *pArg) which is mainly 
  76. for backward compatibility with an older version of MicroThread.
  77.  
  78. MTAddNewThread() returns a thread identifier which is a handle to the 
  79. thread. If it returns zero, then an error has occurred and no new 
  80. thread was created.
  81.  
  82. ---------------------------------------------------------------------
  83.  
  84. void MTKillThread(unsigned threadID);
  85.  
  86. This function just kills the specified thread. Can only be used 
  87. during multi-threading.
  88.  
  89. ---------------------------------------------------------------------
  90.  
  91. void MTEndThread(void);
  92.  
  93. This function kills the current thread.
  94.  
  95. ---------------------------------------------------------------------
  96. void MTEndMultiThreading(void);
  97.  
  98. This kills all known threads dead, i.e., it stops multi-threading, 
  99. and cause MTStartMultiThreading() to return.
  100.  
  101. ---------------------------------------------------------------------
  102.  
  103. Semaphore MTCreateSema(void);
  104.  
  105. This function creates and returns a unique semaphore. A semaphore of 
  106. the following type:
  107.  
  108. typedef unsigned int Semaphore;
  109.  
  110. ---------------------------------------------------------------------
  111.  
  112. unsigned MTDestroySema(Semaphore semaphore);
  113.  
  114. This function destroys the specified semaphore. Trying to destroy a 
  115. semaphore which is still in use, i.e. have threads blocked on it or 
  116. is n possesion by a thread, is an error and will fail. The functon 
  117. return 1 on success, and 0 on failure.
  118.  
  119. ---------------------------------------------------------------------
  120.  
  121. void MTWait(Semaphore Semaphore);
  122.  
  123. This function will acquire the semaphore for the calling thread or 
  124. will cause the thread to block if another thread has acquired the 
  125. semaphore, until the semaphore become free.
  126.  
  127. ---------------------------------------------------------------------
  128. int MTTestAndSet(Semaphore Semaphore);
  129.  
  130. This is similar to MTWait(), except that the calling thread will not 
  131. be block if the semaphore is not free. It return 1 if the thread is 
  132. successful in acquiring the semaphore, zero if not.
  133.  
  134. ---------------------------------------------------------------------
  135.  
  136. void MTSignal(Semaphore Semaphore);
  137.  
  138. This signals(frees) the specified semaphore. The calling thread must 
  139. have possession of the semaphore before calling this function.
  140.  
  141. ---------------------------------------------------------------------
  142.  
  143. unsigned MTEnterCritical(void);
  144. Causes MicroThread to single-threading mode temporarily with only the 
  145. calling thread executing. Zero return value indicates failure - too 
  146. many nested critical sections - > MAX_CRITICAL_NESTING error.
  147.  
  148. ---------------------------------------------------------------------
  149.  
  150. void MTLeaveCritical(void);
  151. Causes MicroThread to revert back to multi-threading.
  152.  
  153. ---------------------------------------------------------------------
  154.  
  155. void MTYield(void);
  156.  
  157. This causes the calling thread to yield to another thread.
  158.  
  159. ---------------------------------------------------------------------
  160.  
  161. void MTSetPreemptive(int bPreempt);
  162.  
  163. MicroThread can be run in either pre-emptive or non pre-emptive 
  164. multi-threading mode. The pre-emptive mode uses the timer interrupt 
  165. to switch between threads. The non-pre-emptive mode only switches 
  166. when MTYield() is called.  The default mode is pre-emptive. If 
  167. MTSetPreemptive() is called with the parameter bPreempt=1, then the 
  168. pre-emptive mode is selected. If MTSetPreemptive() is called with the 
  169. parameter bPreempt=0, then the non pre-emptive mode is selected. This 
  170. function can only be called after MTInitialise() and before 
  171. MTStartMultiThreading().
  172.  
  173. ---------------------------------------------------------------------
  174.  
  175. Semaphore MTGetCRTLibSema(void);
  176.  
  177. This function returns semaphore used in MTCRTLIB.C to serialise 
  178. access to Turbo C's runtime libraries.
  179.  
  180. ---------------------------------------------------------------------
  181.  
  182. unsigned long MTGetClockTick(void);
  183.  
  184. This returns the number of clock ticks since MTStartMultiThreading().
  185. One second is approx. 18.2 clock ticks.
  186.  
  187. ---------------------------------------------------------------------
  188.  
  189. void MTSleep(unsigned long ticks);
  190.  
  191. Puts the current thread to sleep for the specified number of clock 
  192. ticks (at least). The length of time that the thread actually sleeps 
  193. may be a few ticks more depending on however many thread are running 
  194. and what they are doing.
  195.  
  196. ---------------------------------------------------------------------
  197.  
  198. unsigned MTCreateMailbox(char *name);
  199.  
  200. MicroThread supports named mailboxes for sending messages between 
  201. threads. This function creates a mailbox with the specified name, and 
  202. returns a handle to the mailbox. A zero return value indicates 
  203. failure.
  204.  
  205. ---------------------------------------------------------------------
  206.  
  207. unsigned MTDestroyMailbox(unsigned mailboxHnd);
  208.  
  209. This destroys the specified mailbox. Goes without saying that 
  210. destroying a mailbox which is in active use is an error. Return 1 on 
  211. success and zero on failure.
  212.  
  213. ---------------------------------------------------------------------
  214.  
  215. unsigned MTGetMailboxHandle(char *mbxName);
  216.  
  217. Retrieves the handle to the named mailbox. Returns zero if the 
  218. mailbox doesn't exist.
  219.  
  220. ---------------------------------------------------------------------
  221.  
  222. int MTSendMsg(unsigned mailboxHnd, unsigned msgSize, void *pMsg);
  223.  
  224. Sends a message(data) to the specified mailbox. The function doesn't 
  225. return until a reciver has picked up the message (the rendevous 
  226. method). This is also a good way of synchronizing different 
  227. cooperating threads. The message is in the form of a pointer to a 
  228. block of memory of size 'msgSize'. A copy of the message is made by 
  229. the receiver. 
  230.  
  231. ---------------------------------------------------------------------
  232.  
  233. int MTReceiveMsg(unsigned mailboxHnd, unsigned bufferSize, void 
  234. *pBuffer);
  235.  
  236. The counter part to MTSendMsg(). The calling thread will wait until 
  237. there is a message in the mailbox. The memory block specified by the 
  238. message is copied into the buffer pointed to by 'pBuffer'.
  239.  
  240. ---------------------------------------------------------------------
  241.  
  242. The following are functions in MTCRTLIB.C. They are basically 
  243. semaphored-wrappers around the Turbo C runtime library functions.
  244.  
  245. int MTfprintf (FILE *stream, const char *format,...);
  246. int MTprintf (const char *format,...);
  247. int MTfputs(const char *s, FILE *stream);
  248. int MTputs(char *s);
  249. int MTfputc(int c, FILE *stream);
  250. int MTputc(int c);
  251. int MTputchar(int c);
  252. FILE *MTfopen(const char *filename, const char *mode);
  253. int MTfclose(FILE *stream);
  254. int MTfeof(FILE *stream);
  255. int MTsprintf (char *buffer, const char *format,...);
  256. char *MTfgets(char *s, int n, FILE *stream);
  257. int MTfgetc(FILE *stream);
  258. int MTxyputc(int x, int y, int c);
  259. int MTxyputs(int x, int y, const char *s);
  260. int MTxyprintf (int x, int y, const char *format, ...);
  261. int MTkbhit(void);
  262. int MTgetch(void);
  263. char * MTgets(char *buf);
  264. void MTclrscr(void);
  265. int MTrandom(int num);
  266. void *MTmalloc(size_t size);
  267. void MTfree(void *block);
  268. char *MTstrcpy(char *source, char *dest);
  269. size_t MTfread(void *ptr, size_t size, size_t n, FILE *stream);
  270. size_t MTfwrite(const void *ptr, size_t size, size_t n, FILE*stream);
  271.  
  272.